<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
	<title>
		EGF Tutorial - Factory Component. First steps.
	</title>
	<link rel="stylesheet" href="../book.css" charset="ISO-8859-1" type="text/css" />

	<meta name="copyright" content="Copyright (c) Thales Corporate Services S.A.S, 2009. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." />
	<meta name="author" content="Benoit Langlois" />
	<meta name="keywords" content="egf,factory,component"/>
</head>

<body xml:lang="EN-US" lang="EN-US">

<table border="0" cellpadding="2" cellspacing="0" width="100%">
  <tbody>
    <tr>
    	<td colspan="2" align="left" bgcolor="#0080c0" valign="top">
    	  <h2><font face="Arial,Helvetica"><font color="#ffffff">
    	  &nbsp;EGF Tutorial - Factory Component. First steps.
    	  </font></font></h2>
    	</td>
    </tr>
	</tbody>
</table>

<p class="Para">This first tutorial explains how to create and execute simple factory components with EGF.</p>

<br/>

<h2 class="Head">1. Creation of factory component and task</h2>

<h3 class="Head">1.1. Comprehension</h3>
<p class="Para"><i>Generation activities</i>. A generation can be decomposed into generation stages down to the generation leaves which realize the effective generation tasks, such as producing an API. In EGF, this corresponds to <b>factory components</b> which delegate their generations, by an activity invocation, to other factory components until <b>tasks</b> which realize a generation task. A task is implemented in a language, such as Java or Ant.</p>
<p class="Para"><i>Storage</i>. Factory components and tasks are stored in <b>fcore</b> files.</p>

<p align="center">
  <img src="./images/egf_tut_fc_1_1.png" alt="EGF Activity Relationships"/>
</p>
<p align="center"><i>Figure 1. EGF Activity Relationships</i></p>  


<h3 class="Head">1.2. Practice</h3>

<p class="Para">The sequence of actions to <i>create a factory component</i>:</p>
<ul CLASS="UnorderedList">
    <li CLASS="Item">First, create a project and a folder where the factory components and tasks will be located</li>
    <li CLASS="Item">Creation of a Factory Component - Commands: <i>[File][New][Other...]/[EGF folder][EGF Activity]</i></li>
    <li CLASS="Item">Select a project or a project folder, and set the fcore file name</li>
    <li CLASS="Item">Click on Finish or Next, and select <i>Factory Component</i> for model object</li>
    <li CLASS="Item">Click on Finish; the Factory Component is created</li>
    <li CLASS="Item">Set the factory component name in the <i>Properties</i> view to better identify it later</li>
</ul>

<p class="Para">The sequence of actions is the same for a task creation: select <i>Task</i> as model object instead of <i>Factory Component</i>.</p>

<p class="Para">A fcore file is a resource able to contain several activities, i.e. several factory components or tasks. In order to add a new activity in the same fcore file:</p>
<ul CLASS="UnorderedList">
    <li CLASS="Item">Right-Click on an activity - Commands: <i>[New Sibling]</i></li>
    <li CLASS="Item">Select the activity type to create</li>
</ul>
<br/>

<h3 class="Head">1.3. Application</h3>
<p class="Para">During this tutorial, a Java class will be implemented. Then, it is better to start with a Java project.</p>
<p class="Para">Create a <u>Factory component</u> named <i>HelloWorld</i> and a <u>Task</u> named <i>HelloWorldTask</i>.</p>

<p align="center">
  <img src="./images/egf_tut_fc_1_2.png" alt="New EGF Activity"/>
</p>
<p align="center"><i>Figure 2. New EGF Activity</i></p>  
<br/>

<h2 class="Head">2. Creation of task contracts and task implementation</h2>

<h3 class="Head">2.1. Comprehension</h3>

<p class="Para"><i>Contracts</i>. In EGF, an activity parameter is named <b>Contract</b>. Factory component and task contracts are contained in a <i>Contract Container</i>. A <i>Contract</i> has a Name, Mode (IN, OUT, IN_OUT), is mandatory or not, has a <b>Type</b>, and possibly a default value.</p>

<p align="center">
  <img src="./images/egf_tut_fc_1_3.png" alt="Activity Contracts"/>
</p>
<p align="center"><i>Figure 3. Activity Contracts</i></p>  

<p class="Para"><i>Task declaration and implementation</i>. A task realizes an effective work. It is necessary to differentiate the task declaration, defined in a fcore model, from the task implementation, written in a language such as Java. After its declaration, a task can be invoked by different factory components. The task implementation is the means to execute any tool, or any code in the given language. The Java class implements an <i>ITaskProduction</i> interface. It can implement three methods: preExecute, doExecute, postExecute. The task methods have a context parameter to get, set and work with the task contracts. The link between the Task and the implementation class is realized at the task level.</p>

<p align="center">
  <img src="./images/egf_tut_fc_1_4.png" alt="Java Task and Java Task implementation"/>
</p>
<p align="center"><i>Figure 4. Java Task and Java Task implementation</i></p>  


<h3 class="Head">2.2. Practice</h3>
<p class="Para">Task modeling - The sequence of actions to <i>create task contracts</i>:</p>
<ul CLASS="UnorderedList">
    <li CLASS="Item">Creation of the contract container - Command: on a task, <i>[New Child][Contract Container]</i></li>
    <li CLASS="Item">Creation of a contract - Command: on the task contract container, <i>[New Child][Contract]</i></li>
    <li CLASS="Item">Set the contract name, mode, and mandatory values</li>
    <li CLASS="Item">Definition of the contract type - Command: on the contract, <i>[New Child][String|Integer...]</i></li>
    <li CLASS="Item">Set the default value on the contract type with the <i>Value</i> property</li>
</ul>

<h3 class="Head">2.3. Application</h3>
<p class="Para">Create a Task contract 'value' of String contract type with the  (default) value 'World', as shown in the following figure.</p>

<p align="center">
  <img src="./images/egf_tut_fc_1_5.png" alt="Java Task Example"/>
</p>
<p align="center"><i>Figure 5. Java Task Example</i></p>  


<h3 class="Head">2.4. Practice</h3>
<p class="Para">Task implementation - The sequence of actions to <i>create and associate a task Java Class</i>:</p>
<ul CLASS="UnorderedList">
    <li CLASS="Item">Create a Class which implements the <i>ITaskProduction</i> Interface</li>
    <li CLASS="Item">Implement the task class</li>
    <li CLASS="Item">In the fcore of the task, declare the task as a Java Task - Command: on the [Task], set the <i>Task/kind</i> property to <i>java</i></li>
    <li CLASS="Item">Associate the task with the task Java class - Command: on the [Task], on the <i>Implementation</i> property, select a Java task class</li>
</ul>

<p align="center">
  <img src="./images/egf_tut_fc_1_6.png" alt="Java Task / Java class association"/>
</p>
<p align="center"><i>Figure 6. Java Task / Java class association</i></p>  
<p class="Para">At this stage, the task is executable. Cf. section 4.</p>


<h3 class="Head">2.5. Application</h3>
<p class="Para">Create a Java class <i>HelloWorld</i> that displays an parameterized Hello message. Example of code:</p>
				<font color="777777"><pre>
import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.egf.core.EGFCorePlugin;
import org.eclipse.egf.core.producer.InvocationException;
import org.eclipse.egf.ftask.producer.context.ITaskProductionContext;
import org.eclipse.egf.ftask.producer.invocation.ITaskProduction;


public class HelloWorld implements ITaskProduction {

	public void doExecute(ITaskProductionContext productionContext,
			IProgressMonitor monitor) throws InvocationException {
		String value  = productionContext.getInputValue("value", String.class);
		String outputMessage = new String ("Hello " + value + "!");
		// Message on the default console
		System.out.println(outputMessage);
		// Message on the EGF console
	    EGFCorePlugin.getDefault().logInfo(outputMessage); 		  
	}

	public void preExecute(final ITaskProductionContext context, final IProgressMonitor monitor_p) throws InvocationException {
		// TODO Auto-generated method stub

	}

	public void postExecute(final ITaskProductionContext context, final IProgressMonitor monitor_p) throws InvocationException {
		// TODO Auto-generated method stub

	}

}
				</pre></font>

<p class="Para">Associate the <i>HelloWorld</i> class to the <i>HelloWorldTask</i> Java task.</p>

<br/>

<h2 class="Head">3. Task invocation in a factory component</h2>

<h3 class="Head">3.1. Comprehension</h3>
<p class="Para"><i>Orchestration</i>. The same task / factory component can be invoked by different factory components; the same factory component can invoke several factory component and/or tasks. Invocations to factory components and tasks are defined in an orchestration. EGF proposes a simple orchestration type named <b>production plan</b>. A production plan is a sorted list of activity invocations. A <b>task invocation</b> calls a task with the values required by the task contracts.</p>

<p align="center">
  <img src="./images/egf_tut_fc_1_7.png" alt="Factory Component Orchestration"/>
</p>
<p align="center"><i>Figure 7. Factory Component Orchestration</i></p>  


<h3 class="Head">3.2. Practice</h3>

<p class="Para">The sequence of actions to <i>create a production plan</i>:</p>
<ul CLASS="UnorderedList">
    <li CLASS="Item">Commands: on a factory component, <i>[New Child][Production Plan]</i></li>
</ul>

<p class="Para">The sequence of actions to <i>create an invocation</i> in a production plan:</p>
<ul CLASS="UnorderedList">
    <li CLASS="Item">Commands: on a production plan, <i>[Invoke Activity] and select an activity</i>. <i>Next</i> menu allows selecting parameters involved in the invocation.</li>
</ul>

<p class="Para">The sequence of actions to <i>set values</i> for the invocation:</p>
<ul CLASS="UnorderedList">
    <li CLASS="Item">Commands: on an invocation contract, <i>[New Child][the activity contract type, e.g. String]</i></li>
    <li CLASS="Item">Set the value</li>
</ul>

<p class="Para">The two last steps are necessary when the default value of the task contract must be redefined or is undefined and madatory.</p>

<h3 class="Head">3.3. Application</h3>
<p class="Para">In the <i>HelloWorld</i> factory component, create a task invocation without invocation contract (the default value of the task contract is used) and another one with an invocation contract and the associated value.</p>


<br/>

<h2 class="Head">4. Execution of task and factory component</h2>

<h3 class="Head">4.1. Comprehension</h3>
<p class="Para"><i>Execution during the development phase</i>. During the development phase, there exist two modes to execute a task or factory component. 1) Dynamically, directly on a factory component or on a task, when the model is open. This mode is useful to simultaneously develop and test tasks and factory components. Before execution, it is controled that the model is valid. 2) On the fcore resource. This avoids to open the fcore resource.</p>
<p class="Para"><i>Execution on the target platform</i>. After deployment in the target platform, the factory components, tasks, and fcore resources can be normally executed.</p>
<p class="Para"><i>Preferences</i>. The EGF production settings are accessible via the EGF preferences.</p>


<h3 class="Head">4.2. Practice</h3>

<p class="Para">The sequence of actions to <i>execute a task or factory component dynamically</i>:</p>
<ul CLASS="UnorderedList">
    <li CLASS="Item">Commands: <i>[Right-Click][Run EGF Activity...]: on a task or a factory component</i></li>
</ul>


<p class="Para">The sequence of actions to <i>execute a fcore resource</i>:</p>
<ul CLASS="UnorderedList">
    <li CLASS="Item">Commands: <i>[Right-Click][Run EGF Activity...] on the fcore file</i></li>
    <li CLASS="Item">If there are several factory components or tasks in the same fcore file, then it is necessary to select the activity to be executed</li>
</ul>

</body>
</html>
